/**
 * @file		spi.h
 * @brief		SPI
 * @note		None
 * @attention	None
 * 
 * <B><I>ALL RIGHTS RESERVED, COPYRIGHT&copy; SOCIONEXT INCORPORATED 2016</I></B>
 */


/** @weakgroup spi_overview
@{
	SPI base function.<br>
	Transmission and reception of data by the SPI.<br>
	<br>
	Control parameter setting<br>
	- Transmit Mode : Mode3<br>
		 - Clock Polarity = 1<br>
		 - Clock Phase = 1<br>
		 - Data are captured on clock's rising edge and data is output on a falling edge.<br>
	- Enable signal selection : Use CPU (software)<br>
	- Bit direction : MSB first<br>
	- Data length : 8 bit length<br>
	- Serial Clock Divisor : 50Mbps<br>
	- Inter-Transfer Delay enable : Disable delay (full speed)<br>
	- SCLK cycles for Inter-transfer delay : 0<br>
	- Inhibit the RX FIFO : Inhibit(Send) / Not inhibit(Receive)<br>
	- TX/RX FIFO depth : 64<br>
	- TX FIFO Watermark value : 0<br>
	- RX FIFO Watermark value : 8<br>
	- DMA Enable : Disable<br>
	- DMA Receive Timeout : 0<br>
	- Continuous Transfer enable : ssOut goes inactive between successive transfers<br>
	- Slave Select Output selection : Select Slave for TX/RX<br>
	- Slave Select Polarity selection : SSOUT/SSIN is an active Low<br>
@}*//* --- end of spi_overview */

/** @weakgroup spi_sequence
@{
	- @ref spi_send_sequence
	- @ref spi_receive_sequence
	- @ref spi_sample
	
	@section spi_send_sequence Sequence example of SPI Transmission.
	@image html spi_send.png
	<br>
	@section spi_receive_sequence Sequence example of SPI Reception.
	@image html spi_receive.png
	<br>

	<hr>
	@section spi_sample Sample code
	The example of SPI is as follows.

	@code
	void SPI_Send_Sample()
	{
		int ret;
		T_SPI_SEND_BUFFER buff;
		
		// set Buffer.
		buff.address = 0xXXXXXXXX;
		buff.size = 10;
		ret = iSPISetSendBuffer(&buff);
		if (ret != 0) {
			return;
		}
		
		// set notification : enable.
		ret = iSPISendNotification(1);
		if (ret != 0) {
			return;
		}
		
		// Send start.
		iSPISendStart();
	}
	
	void SPI_Receive_Sample()
	{
		int ret;
		T_SPI_RECEIVE_BUFFER buff;
		
		// set Buffer.
		buff.address = 0xXXXXXXXX;
		buff.size = 0xFF;
		buff.pointer = 0xXXXXXXXX;
		buff.size = 0;
		ret = iSPISetReceiveBuffer(&buff);
		if (ret != 0) {
			return;
		}
		
		// set notification : enable.
		ret = iSPIReceiveNotification(1);
		if (ret != 0) {
			return;
		}
		
		// Receive start.
		ret = iSPIReceiveStart();
		if (ret != 0) {
			iSPIReceiveStop();
			return;
		}
	}
	@endcode

@}*//* --- end of spi_sequence */

#ifndef _SPI_H_
#define _SPI_H_

/** @weakgroup spi_definition
@{*/

/** Send Buffer data */
typedef struct {
	unsigned long		address;		/**< start address of buffer.	*/
	unsigned long		size;			/**< byte size. 0:no-buffer.	*/
} T_SPI_SEND_BUFFER;

/** Receive Buffer data */
typedef struct {
	unsigned long		address;		/**< start address of buffer.					*/
	unsigned long		size;			/**< byte size. 0:no-buffer.					*/
	unsigned long		pointer;		/**< address of write pointer.					*/
	int					overlap;		/**< 0:no-overlap, 1:cyclic, 2:same position	*/
} T_SPI_RECEIVE_BUFFER;

/* @} */	// spi_definition group

/** @weakgroup spi_func
@{*/

/**
SPI Send start.
@retval  0 : success
@retval  1 : parameter error
@retval  3 : function error
*/
extern int iSPISendStart(void);

/**
SPI Receive start.
@retval  0 : success
@retval  1 : parameter error
@retval  3 : function error
*/
extern int iSPIReceiveStart(void);

/**
SPI Receive stop.
@retval  0 : success
*/
extern int iSPIReceiveStop(void);

/**
set SPI Send notification.
@param [in]	enable		notification enable.<br>
						0:disable, 1:enable
@retval  0 : success
@retval  1 : parameter error
*/
extern int iSPISendNotification(int enable);

/**
set SPI Receive notification.
@param [in]	enable		notification enable.<br>
						0:disable, 1:enable
@retval  0 : success
@retval  1 : parameter error
*/
extern int iSPIReceiveNotification(int enable);

/**
set SPI input buffer for send.
@param [in]	buff		Send buffer data.
@retval  0 : success
@retval  1 : parameter error
*/
extern int iSPISetSendBuffer(T_SPI_SEND_BUFFER const* const buff);

/**
set SPI input buffer for receive.
@param [in]	buff		Receive buffer data.
@retval  0 : success
@retval  1 : parameter error
*/
extern int iSPISetReceiveBuffer(T_SPI_RECEIVE_BUFFER const* const buff);

/* @} */	// spi_func group

#endif	// _SPI_H_
